home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / wpshell.arc / SHELL.PRN < prev   
Encoding:
Text File  |  1987-01-21  |  32.9 KB  |  1,218 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.               SHELL PROGRAM INTERFACE
  31.  
  32.                                WordPerfect Corporation
  33.  
  34.  
  35.                                              Version 1.0
  36.                                            February, 1986
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.         SHELL PROGRAM INTERFACE -- TECHNICAL SPECIFICATION
  45.  
  46.             This specification contains the information necessary to write programs that
  47.             interact with WordPerfect's Shell program manager.  The following summary lists
  48.             the information contained in each chapter of this document.
  49.  
  50.  
  51.         Chapter 1 -- Introduction to the Shell
  52.  
  53.             This chapter introduces the Shell program manager in general, it's capabilities,
  54.             and the benefits to be gained by writing programs that interact directly with the
  55.             Shell.
  56.  
  57.         Chapter 2 -- Writing programs that interact with the Shell
  58.  
  59.             This chapter gives some basic guidelines for writing programs that interact with
  60.             the Shell.  It contains the general steps necessary for a program to interface to
  61.             the Shell.
  62.  
  63.         Chapter 3 -- Testing for the presence of the Shell
  64.  
  65.             This chapter describes the method that programs should use to determine if the
  66.             Shell is present in the system.  An example procedure (in assembly language) is
  67.             given to illustrate the method.
  68.  
  69.         Chapter 4 -- Shell Functions
  70.  
  71.             This chapter details each of the available Shell functions, and gives the input
  72.             parameters, results, possible error codes, and examples in assembly language for
  73.             each.
  74.  
  75.         Chapter 5 -- User Interface guidelines and suggestions
  76.  
  77.             This chapter gives some basic guidelines on implementing the Shell interface so
  78.             that the user will be able to take advantage of all of the Shell's capabilities.
  79.  
  80.         Appendix
  81.  
  82.                  A - File Formats for the Clipboard
  83.                  B - Memory Considerations
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.                                                   2
  97.  
  98.  
  99.  
  100.  
  101.  
  102.         CHAPTER 1 -- INTRODUCTION TO THE SHELL
  103.  
  104.  
  105.             The Shell is a program manager/integrator developed by WordPerfect Corporation
  106.             to help integrate WordPerfect, MathPlan, and other programs.  
  107.  
  108.             The Shell provides the user with a program menu from which programs, DOS
  109.             commands, batch files, and utilities can be executed.  The user can setup the
  110.             menu to include whatever programs he or she wishes.
  111.  
  112.             The user can load several programs into memory concurrently, and switch
  113.             between those programs at will under the Shell.  The Shell also provides a
  114.             "clipboard", or buffer, for moving data (text, numbers, graphs, etc.) easily
  115.             between programs.
  116.  
  117.             Included with the Shell in the WordPerfect Library package are several desktop
  118.             utility programs, such as a calculator, a calendar, a notebook, a DOS file
  119.             manager, and others -- all of which can cut and paste information to and from
  120.             the clipboard.
  121.  
  122.             A program that can interact directly with the Shell can take advantage of the
  123.             following features and capabilities:
  124.  
  125.                  1.   Suspend operation and transfer control to the Shell manager.  This
  126.                       allows the user to load other programs concurrently and switch back
  127.                       and forth between programs with the press of a key.  For example,
  128.                       the user is able to pop into any of the desktop utilities (calculator,
  129.                       calendar, notebook, etc.) that are included with the Shell.
  130.  
  131.                  2.   Write or append ASCII text to the Shell's clipboard.  This allows the
  132.                       user to easily move data from one program to another.
  133.  
  134.                  3.   Retrieve a copy of text in the Shell's clipboard.
  135.  
  136.                  4.   Take of advantage of Expanded Memory, if available.  If the user has
  137.                       an Intel AboveBoard (c), or other Expanded Memory board that meets
  138.                       the Lotus/Intel/Microsoft Specification, the Shell will automatically
  139.                       swap programs out to the the expanded memory above 640K.  This
  140.                       allows the user to load up many more programs at once than would
  141.                       normally fit in 640K of conventional memory.
  142.  
  143.             All programs, even those that do not interact directly with the Shell, can take
  144.             advantage of the following Shell features and capabilities:
  145.  
  146.                  1.   Start the program from the Shell menu with the press of a key.  The
  147.                       user can specify which directory to make the new default directory
  148.                       before starting the program.  Command line arguments can also be
  149.                       specified for each program on the Shell menu.  The user can also
  150.                       create sub-menus for organizing their hard disk and programs in
  151.                       logical groupings.
  152.  
  153.  
  154.  
  155.                                                   3
  156.  
  157.  
  158.  
  159.  
  160.  
  161.                  2.   Use the Shell keyboard macro facility.  This allows the user to define
  162.                       a series of keystrokes and assign them to either an ALT-SHIFT-letter
  163.                       combination or to a filename on disk.  The keystrokes that were
  164.                       recorded can be played back from any program.  There is no limit
  165.                       (except disk space) to the number or length of Shell macros that can
  166.                       be created.
  167.  
  168.                  3.   Execute DOS commands, batch files, or Shell utilities from the Shell
  169.                       menu.
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.                                                   4
  215.  
  216.  
  217.  
  218.  
  219.  
  220.          CHAPTER 2 -- WRITING PROGRAMS THAT INTERACT WITH
  221.                       THE SHELL
  222.  
  223.  
  224.             In order for a program to interact directly with the Shell, it must perform the
  225.             following basic steps:
  226.  
  227.                  1.   Test to see whether or not the Shell is present in the system.  A
  228.                       method for doing this is described in detail in Chapter 3.
  229.  
  230.                  2.   If the Shell is present, use Function 50h to request a unique program
  231.                       ID code.  This code is then used in subsequent function calls to the
  232.                       Shell.
  233.  
  234.                  3.   Release any memory that is not needed.  The program should
  235.                       determine what memory it needs for data, buffers, etc., and release
  236.                       any extra memory using DOS function 4Ah.
  237.  
  238.                       When DOS loads a program into memory, all available memory is
  239.                       assigned to that program.  In order for the Shell to be able to load
  240.                       other programs concurrently into memory, programs that interact with
  241.                       the Shell must release extra memory by "shrinking" down with DOS
  242.                       function 4Ah.  This should be done as soon as the program determines
  243.                       that it has been loaded under the Shell.
  244.  
  245.                       Most WordPerfect programs use less memory for buffers, etc. when
  246.                       loaded under the Shell than they do when loaded normally from DOS. 
  247.                       This makes it possible to load several program concurrently under the
  248.                       Shell.
  249.  
  250.                  4.   Use Shell Function 57h to determine if the Shell is loading the
  251.                       program as part of a "start-up" procedure.  If so, the program should
  252.                       do any initialization, then transfer control back to the Shell (using
  253.                       Function 50h) before modifying the screen or asking for any user
  254.                       input.
  255.  
  256.                  5.   Check user input where applicable for the "Shell" key (Ctrl-F1) and
  257.                       use the Shell functions to interact with the Shell (i.e., go to Shell
  258.                       temporarily, write or append data to the clipboard, get data from the
  259.                       clipboard, etc.)
  260.  
  261.                  6.   Before terminating, the program should issue Function 55h (Request
  262.                       permission to exit) so that the Shell can insure that all programs exit
  263.                       in the reverse order that they were loaded into memory.  This is
  264.                       necessary for DOS to operate properly.
  265.  
  266.             Chapters 3 and 4 describe how to test for the Shell and make function calls to
  267.             the Shell.
  268.  
  269.  
  270.  
  271.  
  272.  
  273.                                                   5
  274.  
  275.  
  276.  
  277.  
  278.  
  279.         CHAPTER 3 -- TESTING FOR THE PRESENCE OF THE SHELL
  280.  
  281.             This chapter describes how to use the DOS "get interrupt vector" technique to
  282.             test whether or not the Shell is present.  Any program can use these steps to
  283.             test for the presence of the Shell.
  284.  
  285.             1.   Use the DOS "get interrupt vector" command (DOS function 35h) to get the
  286.                  contents of interrupt vector number 1Ah (addresses 0000:0068 through
  287.                  0000:006B).
  288.  
  289.                  The Shell uses this interrupt vector to perform all interaction between
  290.                  application programs and the Shell manager.  The OFFSET of the interrupt
  291.                  service routine address is stored in the word located at address 0000:0068h;
  292.                  the SEGMENT address is stored in the word located at address 0000:006Ah.
  293.  
  294.             2.   Compare the contents of an ASCII string which starts at the address
  295.                  specified by the contents of the interrupt vector 1Ah plus a fixed offset of
  296.                  2 bytes to the string "SHELL001".
  297.  
  298.                  If the result of the string comparison is positive, the Shell is present and
  299.                  can be called via interrupt 1Ah.
  300.  
  301.  
  302.         Example
  303.  
  304.             The following code is an example of the technique described above to determine
  305.             if the Shell is present.
  306.  
  307.             ;****************************************************************
  308.             ;
  309.             ;    The following procedure determines whether or not the Shell
  310.             ;    is present in the system.  
  311.             ;
  312.             ;    RESULT:   CARRY FLAG is SET   if the Shell is present
  313.             ;              CARRY FLAG is CLEAR if the Shell is not present
  314.             ;
  315.             ;****************************************************************
  316.  
  317.             Test_For_Shell PROC NEAR
  318.  
  319.                  PUSH      AX
  320.                  PUSH      BX
  321.                  PUSH      CX
  322.                  PUSH      SI
  323.                  PUSH      DI
  324.                  PUSH      DS
  325.                  PUSH      ES
  326.  
  327.                  PUSH      CS
  328.                  POP       DS             ; prepare DS for string compare
  329.  
  330.                  MOV       AH,35h
  331.  
  332.                                                   6
  333.  
  334.  
  335.  
  336.  
  337.  
  338.                  MOV       AL,1Ah         ; issue "get interrupt vector"
  339.                  INT       21h
  340.  
  341.                  MOV       DI,BX
  342.                  ADD       DI,2
  343.  
  344.                  MOV       SI,OFFSET ascii_name
  345.  
  346.                  MOV       CX,8
  347.                  CLD
  348.                  REPE      CMPSB
  349.                  JNE       Test_No
  350.  
  351.             Test_Yes:
  352.                  STC
  353.                  JMP       Test_Exit
  354.  
  355.             Test_No:
  356.                  CLC
  357.  
  358.             Test_Exit:
  359.                  POP       ES
  360.                  POP       DS
  361.                  POP       DI
  362.                  POP       SI
  363.                  POP       CX
  364.                  POP       BX
  365.                  POP       AX
  366.                  RET
  367.  
  368.             ascii_name: DB "SHELL001"
  369.  
  370.             Test_For_Shell ENDP
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.                                                   7
  392.  
  393.  
  394.  
  395.  
  396.  
  397.         CHAPTER 4 -- SHELL FUNCTIONS
  398.  
  399.  
  400.             All interaction with the Shell manager is performed by issuing interrupt 1Ah. 
  401.             The contents of the registers before and after issuing the interrupt will vary
  402.             depending on the Shell function being called.  The function number is always
  403.             passed in register AH.  For all functions except Function 50h (Get Program ID),
  404.             the program ID code is passed in register AL.
  405.  
  406.             For all functions, register AH returns an error status code.  The possible error
  407.             status codes are listed for each function.  In general, if AH is zero, the function
  408.             executed normally.  If AH is non-zero, an error of some kind occurred.  
  409.  
  410.             For all functions, if AH is 0FFh on return, an invalid Function code number was
  411.             passed in AH.
  412.  
  413.             For each function, the input parameters, results, possible error codes, and an
  414.             example in assembly language are given.
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.                                                   8
  451.  
  452.  
  453.  
  454.  
  455.  
  456.         Function 50h -- Get Program ID
  457.  
  458.  
  459.             This function is used to return a unique program ID code to the caller.  This
  460.             should be the first function used by the calling program, and should be called as
  461.             soon as the program determines that the Shell is present.
  462.  
  463.             For all subsequent function calls, the program ID code should be passed in
  464.             register AL.
  465.  
  466.  
  467.             IN:       AH contains the function number (50h)
  468.  
  469.             OUT:      AL contains the Program ID code
  470.                       AH contains an error code
  471.  
  472.             EXAMPLE:
  473.  
  474.                       MOV  AH,50h
  475.                       INT  1Ah
  476.                       OR   AH,AH
  477.                       JNZ  error_handler
  478.  
  479.             ERROR CODES:
  480.  
  481.                       AH = 0    No error.
  482.                       AH = 1    No Program ID code available.
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.                                                   9
  510.  
  511.  
  512.  
  513.  
  514.  
  515.         Function 51h -- Go to Shell
  516.  
  517.  
  518.             This function is used to temporarily suspend the calling program and transfer
  519.             control to the Shell manager.  The Shell menu will be displayed and the user is
  520.             allowed to select from among the entries on the menu.
  521.  
  522.             When the user elects to return to the calling program, the Shell transfers
  523.             control back to the caller by returning from the interrupt.
  524.  
  525.             It is very important that the calling program check the error status code in AH
  526.             on return from this interrupt.  The user may have elected to exit all programs
  527.             that are loaded under the Shell, in which case the caller will need to "close up
  528.             shop" and terminate.
  529.  
  530.             IN:       AH contains the function number (51h)
  531.                       AL contains the Program ID (returned by Function 50h)
  532.  
  533.             OUT:      AH contains an error code
  534.  
  535.             EXAMPLE:
  536.  
  537.                       MOV  AH,51h
  538.                       MOV  AL,program_ID
  539.                       INT  1Ah
  540.                       OR   AH,AH
  541.                       JZ   continue_with_program
  542.                       DEC  AH
  543.                       JZ   unable_to_transfer_to_shell
  544.                       DEC  AH
  545.                       JZ   exit_program
  546.                       DEC  AH
  547.                       JZ   exit_program_but_save_info_first
  548.  
  549.             ERROR CODES:
  550.  
  551.                       AH = 0    No error, continue with program.
  552.                       AH = 1    Unable to transfer control to Shell -- continue with
  553.                                 program or issue error message.
  554.                       AH = 2    User wishes to exit all programs that are loaded under the
  555.                                 Shell.  Close up files, etc., and terminate.
  556.                       AH = 3    User wishes to save any information (documents, worksheets,
  557.                                 etc.) that has been modified, and then exit all programs that
  558.                                 are loaded under the Shell.  Save any updated information
  559.                                 (this may require user interaction), and terminate.
  560.  
  561.             Note: When this function is called, the Shell saves the following information
  562.             about the caller's "state" on the caller's stack:
  563.  
  564.                       1. ALL registers except AX
  565.                       2. All flags
  566.                       3. The current cursor position and mode
  567.  
  568.                                                  10
  569.  
  570.  
  571.  
  572.  
  573.  
  574.                       4. The current DOS DTA address
  575.                       5. The following interrupt vectors:
  576.                            - Divide overflow
  577.                            - Critical error handler
  578.  
  579.             The above "state" is restored before the Shell returns control to the caller.
  580.  
  581.             If AH contains a 2 or 3 (terminate) code on return from this function, the
  582.             calling program should still issue Function 55h (Request permission to exit)
  583.             before actually terminating.
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.                                                  11
  628.  
  629.  
  630.  
  631.  
  632.  
  633.         Function 52h -- Write Data to Clipboard
  634.  
  635.  
  636.             Use this function to write the data specified by DS:SI and CX registers to the
  637.             clipboard.  Any previous information contained in the clipboard is lost.  Use
  638.             Function 53h to append or add data to the clipboard.
  639.  
  640.             The clipboard is virtual in nature, so if the data is too large for the 5K memory
  641.             buffer reserved for the clipboard, a temporary file will automatically be created
  642.             on disk, and the additional information will be stored there.
  643.  
  644.  
  645.             IN:       AH contains the function number (52h)
  646.                       AL contains the Program ID code
  647.                       BL contains a format type code as follows:
  648.                            1 = data is in WP text format
  649.                            2 = data is in WP Merge File format
  650.                            3 = data is in ASCII text format
  651.                            (see Appendix for explanation of format codes)
  652.  
  653.                       CX contains the number of bytes to write
  654.                            Note: Calling programs should write or append no more than 5K
  655.                            bytes at a time to the clipboard.  The amount of data that can
  656.                            be stored in the clipboard is limited only by disk space, but the
  657.                            maximum "chunk" that the Shell can handle per call is 5K bytes.
  658.                       DS:SI contains the segment and offset of the location in memory
  659.                       where the data to be written is stored.
  660.  
  661.             OUT:      AH contains an error code
  662.  
  663.             EXAMPLE:
  664.  
  665.                       MOV  AH,52h
  666.                       MOV  AL,program_ID
  667.                       MOV  BL,format_type
  668.                       MOV  CX,number_of_bytes
  669.                       MOV  SI,offset_of_data        ; DS is segment of data
  670.                       INT  1Ah
  671.                       OR   AH,AH
  672.                       JNZ  error_handler
  673.  
  674.             ERROR CODES:
  675.  
  676.                       AH = 0    No error.
  677.                       AH = 1    No room to add data to clipboard (Disk Full error).
  678.                       AH = 2    Invalid format type.
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.                                                  12
  687.  
  688.  
  689.  
  690.  
  691.  
  692.         Function 53h -- Append Data to Clipboard
  693.  
  694.  
  695.             This function is similar to Function 52h, but appends the data to the end of the
  696.             clipboard.
  697.  
  698.             IN:       AH contains the function number (53h)
  699.                       AL contains the Program ID code
  700.                       BL contains a format type code as follows:
  701.                            1 = data is in WP text format
  702.                            2 = data is in WP Merge File format
  703.                            3 = data is in ASCII text format
  704.                            (see Appendix for explanation of format codes)
  705.  
  706.                       CX contains the number of bytes to write
  707.                            No more than 5K bytes at a time (see note under Function 52h -
  708.                            - Write to Clipboard)
  709.                       DS:SI contains the segment and offset of the location in memory
  710.                       where the data to be appended is stored.
  711.  
  712.             OUT:      AH contains an error code
  713.  
  714.             EXAMPLE:
  715.  
  716.                       MOV  AH,53h
  717.                       MOV  AL,program_ID
  718.                       MOV  BL,format_type
  719.                       MOV  CX,number_of_bytes
  720.                       MOV  SI,offset_of_data        ; DS is segment of data
  721.                       INT  1Ah
  722.                       OR   AH,AH
  723.                       JNZ  error_handler
  724.  
  725.             ERROR CODES:
  726.  
  727.                       AH = 0    No error.
  728.                       AH = 1    No room to add data to clipboard (Disk Full error).
  729.                       AH = 2    Invalid format type.
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.                                                  13
  746.  
  747.  
  748.  
  749.  
  750.  
  751.         Function 54h -- Retrieve Data from Clipboard
  752.  
  753.  
  754.             Use this function to retrieve data from the clipboard.  The number of bytes is
  755.             returned in CX.  The calling program should continue making this function call
  756.             until CX equals 0, meaning there is no more data to be retrieved from the
  757.             clipboard.  If CX is zero on the first call, the clipboard is empty.
  758.  
  759.             Function 56h can be used to determine whether the data in the clipboard is in a
  760.             text format (WP or ASCII) or in a mail-merge format (WP Merge File).
  761.  
  762.             IN:       AH contains the function number (54h).
  763.                       AL contains the Program ID code.
  764.                       BL contains a format type code as follows:
  765.                            1 = request data in WP text format
  766.                            2 = request data in WP Merge File format
  767.                            3 = request data in ASCII text format
  768.                            (see Appendix for explanation of format codes)
  769.  
  770.             OUT:      AH contains an error code
  771.                       CX contains number bytes of data returned (0 = empty)
  772.                            Note: The Shell will hand back approximately 128 bytes at a time. 
  773.                            The program should continue calling Function 54h until CX = 0.
  774.                       ES:DI contains the segment and offset of the buffer where the data is
  775.                       located.
  776.  
  777.             EXAMPLE:
  778.  
  779.             Read_clipboard:
  780.                       MOV  AH,54h
  781.                       MOV  AL,program_ID
  782.                       MOV  BL,format_type
  783.                       INT  1Ah
  784.                       OR   AH,AH
  785.                       JNZ  error_handler
  786.                       JCXZ no_more_data
  787.  
  788.                       ; PROCESS CX BYTES AT ES:DI
  789.  
  790.                       JMP  Read_clipboard
  791.             no_more_data:
  792.  
  793.             ERROR CODES:
  794.  
  795.                       AH = 0    No error.
  796.                       AH = 1    Disk I/O error -- can't retrieve data
  797.                       AH = 2    Invalid format type request (i.e., requested data in WP
  798.                                 Merge File format when data in clipboard was WP text or
  799.                                 ASCII text)
  800.  
  801.  
  802.  
  803.  
  804.                                                  14
  805.  
  806.  
  807.  
  808.  
  809.  
  810.         Function 55h -- Request Permission to Exit
  811.  
  812.  
  813.             Because the Shell uses DOS to load programs and manage memory, programs must
  814.             be exited in the reverse order that they were loaded into memory.  This requires
  815.             that a program request permission from the Shell just prior to terminating.  The
  816.             Shell will return control to the program when it is time to exit.
  817.  
  818.             IN:       AH contains the function number (55h)
  819.                       AL contains the Program ID code
  820.  
  821.             OUT:      AH contains an error code
  822.  
  823.             EXAMPLE:
  824.  
  825.                       MOV  AH,55h
  826.                       MOV  AL,program_ID
  827.                       INT  1Ah
  828.                       OR   AH,AH
  829.                       JNZ  go_ahead_and_terminate
  830.                       JMP  restart_program
  831.  
  832.             ERROR CODES:
  833.  
  834.                       AH = 0    Restart program -- user wishes to re-enter program.
  835.                       AH <> 0   Go ahead and terminate program.
  836.  
  837.             Note: The calling program should use DOS function 4Ch to terminate.
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.                                                  15
  864.  
  865.  
  866.  
  867.  
  868.  
  869.         Function 56h -- Check Clipboard Format
  870.  
  871.  
  872.             Use this function to return a format type code indicating what type of data is
  873.             currently in the clipboard (text or mail merge format).
  874.  
  875.             IN:       AH contains the function number (56h)
  876.                       AL contains the Program ID code
  877.  
  878.             OUT:      AH contains the format type code:
  879.                            0 = data is text (WP or ASCII)
  880.                            1 = data is mail-merge format (WP Merge)
  881.  
  882.             EXAMPLE:
  883.  
  884.                       MOV  AH,56h
  885.                       MOV  AL,program_ID
  886.                       INT  1Ah
  887.  
  888.             ERROR CODES:
  889.  
  890.                       No errors are defined for this function
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.                                                  16
  923.  
  924.  
  925.  
  926.  
  927.  
  928.         Function 57h -- Check if Shell is installing program resident
  929.  
  930.  
  931.             This function should be issued by the calling program after it has requested a
  932.             program ID code, and after it has released any extra memory, but before it
  933.             modifies the screen or does any user interaction.
  934.  
  935.             If the function returns a 1 in AL, the user wants to load this program into
  936.             memory as he (she) is starting the Shell, but does not wish to begin using the
  937.             program until they select it from the Shell menu.  If this is the case, the calling
  938.             program should go ahead and complete any initialization required, and then use
  939.             Function 1 to transfer control to the Shell manager.
  940.  
  941.             IN:       AH contains the function number (57h)
  942.                       AL contains the Program ID code
  943.  
  944.             OUT:      AH contains an error code
  945.                       AL = 1 if program should transfer control to Shell immediately before
  946.                       starting.
  947.  
  948.             EXAMPLE:
  949.  
  950.                       MOV  AH,57h
  951.                       MOV  AL,program_ID
  952.                       INT  1Ah
  953.                       OR   AH,AH
  954.                       JNZ  error_handler
  955.                       OR   AL,AL
  956.                       JZ   continue_with_program
  957.  
  958.                       MOV  AH,51h              ; transfer to Shell
  959.                       MOV  AL,program_ID
  960.                       INT  1Ah
  961.                       OR   AH,AH
  962.                       JZ   continue_with_program
  963.                       DEC  AH
  964.                       JZ   continue_with_program
  965.                       DEC  AH
  966.                       JAE  exit_program
  967.  
  968.             continue_with_program:
  969.  
  970.             ERROR CODES:
  971.  
  972.                       AH = 0    No error
  973.                       AH = 1    Invalid program ID code
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.                                                  17
  982.  
  983.  
  984.  
  985.  
  986.  
  987.         Function 58h -- Test if Shell is using Expanded Memory
  988.  
  989.  
  990.             This function allows programs to determine whether or not the Shell is using
  991.             Expanded Memory.  If so, the programs do not need to release memory when
  992.             they start, but can take as much or all of the 640K conventional memory as they
  993.             wish.
  994.  
  995.             IN:       AH contains the function number (58h)
  996.  
  997.             OUT:      AL contains 1 if Expanded Memory is being used.
  998.  
  999.             EXAMPLE:
  1000.  
  1001.                       MOV  AH,58h
  1002.                       INT  1Ah
  1003.                       OR   AL,AL
  1004.                       JZ   no_expanded_memory
  1005.                       JMP  can_use_all_conventional_memory
  1006.  
  1007.             ERROR CODES:
  1008.  
  1009.                       No errors are defined for this function
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.                                                  18
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.           CHAPTER 5 --     USER INTERFACE GUIDELINES AND
  1047.                            SUGGESTIONS
  1048.  
  1049.  
  1050.             All programs (to date) that interact with the Shell use Ctrl-F1 as the "Shell"
  1051.             key.  We highly recommend that all programs that interact with the Shell use
  1052.             Ctrl-F1 to go to the Shell, interact with the clipboard, etc.
  1053.  
  1054.             One of the features of the Shell is the capability for the user to switch between
  1055.             programs by pressing an ALT-SHIFT-letter key combination.  This feature is
  1056.             implemented as a Shell macro, and assumes that the normal procedure to go to
  1057.             the Shell consists of pressing Ctrl-F1 and then 1.  For this reason, we also
  1058.             recommend that a menu be displayed when the user presses Ctrl-F1, where the
  1059.             first option is Go to Shell.  This will allow the user to use the "shortcut"
  1060.             method of switching to and from your program.
  1061.  
  1062.             We suggest that programs which intend to support the Shell directly look
  1063.             through the Shell User's Manual (particulary the Program Profiles in the
  1064.             Appendix) to get a feel for how WordPerfect programs interact with the Shell.
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.                                                  19
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.                                  APPENDIX
  1106.  
  1107.         A. File Formats
  1108.  
  1109.  
  1110.             Information can be passed to and retrieved from the clipboard in one of the
  1111.             following formats:
  1112.  
  1113.                  1. WP Text -- WordPerfect Text format.  Data in this format contains text
  1114.                  characters interspersed with WordPerfect function codes.  WordPerfect
  1115.                  function codes range from 128 to 255 decimal.  "Extended characters" which
  1116.                  would normally occupy this range are preceeded and followed by a special
  1117.                  "gate" -- the function code 0E1h.  Newlines are indicated by a single
  1118.                  linefeed (0Ah).  Only programs which are familiar with WordPerfect
  1119.                  function codes should attempt to read or write to the clipboard using this
  1120.                  format.
  1121.  
  1122.                  2. WP Merge File -- WordPerfect mail-merge format.  This is the same as
  1123.                  WP Text (text interspersed with WP function codes), but the text is
  1124.                  formatted into a field & record orientation.  A ^R and linfeed (0Ah) follow
  1125.                  each field and a ^E and linefeed (0Ah) follow each record.  This format
  1126.                  should only be used by programs which are able to strip out WordPerfect
  1127.                  function codes.
  1128.  
  1129.                  3. ASCII Text -- ASCII Text format.  Data in this format consists of
  1130.                  normal ASCII text.  Newlines are represented by a carriage return
  1131.                  (0Dh)/linefeed (0Ah) combination.  Codes above 128 are assumed to be
  1132.                  extended characters (foreign, line-drawing characters, etc.)  This format can
  1133.                  and should be used by all programs which need to communicate with the
  1134.                  clipboard, but do not wish to worry about WordPerfect function codes.
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.                                                  20
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.         B. Memory Considerations
  1165.  
  1166.             As explained in Chapter 2, programs which interact with the Shell need to
  1167.             release any memory that they do not need when they start.  Many programs
  1168.             normally take all available memory.  In this case, the program should make
  1169.             exception when being loaded under the Shell, take a reasonble amount of memory
  1170.             (or allow the user to specify how much to use) and release the rest for use by
  1171.             other Shell programs.  
  1172.  
  1173.             The Shell itself takes about 25K of memory.
  1174.  
  1175.             The Shell supports the Lotus/Intel/Microsoft Expanded Memory Specification. 
  1176.             The Shell will automatically sense if Expanded Memory is availabe and swap
  1177.             programs out to Expanded Memory when necessary.  When the Shell is run from
  1178.             Expanded Memory, each program can use all or as much of the 640K
  1179.             conventional memory as it desires.  When programs are not currently running
  1180.             they are swapped out to Expanded Memory by the Shell.
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.                                                  21
  1218.